Compendium Deluxe 1

home *** CD-ROM | disk | FTP | other *** search

/ Compendium Deluxe 1 / LSD Compendium Deluxe 1.iso / a / programming / misc / m2_part1.lha / modula / dice / dice.LHA / doc / dcc.doc < prev next >

Wrap

Text File | 1991-04-05 | 26.3 KB | 683 lines

dcc/dcc dcc/dcc DCC.DOC Matthew Dillon 891 Regal Rd. Berkeley, Ca. 94708 USA dillon@overload.Berkeley.CA.US --or-- uunet.uu.net!overload!dillon BIX: mdillon DCC <options and files> NOTE: new this version, use of single precision IEEE libraries for floating point. Please read the note under the option '-ffp' for more information. DCC is similar to the UNIX 'cc' command and is the frontend for the DICE compiler. For best performance I strongly suggest that you make DCC, DC1, DCPP, DAS, and DLINK resident. If you do not have enough memory to do so you at least want to leave the largest programs, DC1 and DAS resident. It is suggested that your machine have at least 1MB of memory. A compile or link can take as much as 400K of run-time memory. Options may occur anywhere on the command line but MUST occur singly. That is, -c -a instead of -ca. file arguments to options may occur with or without an intervening space. -oFILE and -o FILE are both legal. Files ending in .a[sm] are assumed to be assembly files. Files ending in .l[ib] are assumed to be library files. Files ending in .o[bj] are assumed to be object files. All other files are assumed to be C source files. Normally DCC compiles all C source files, assembles all .a[sm] files, and links the resulting object files with any specified .o files together to produce an executable. The output file may optionally be specified with the -o option. If not specified, a default output filename based on the name of the input file is generated. This general action is modified by two options: -c DCC does NOT link, -o specifies the output object file -a DCC does NOT assemble (i.e. leaves the .a file resulting from a compile). -o specifies the output assembly file If neither option is given -o specifies the name of the resulting executable. The default object directory is T: and may be changed with the -O option. The default temporary directory is also T: and may be changed with the -T option. IF YOU HAVE LIMITED MEMORY you may have to specify that temporary files not be placed in T: either by re-assigning T: or using the -T option. DICE goes much slower if temporary files must be written to a floppy or even a hard disk. WARNING: .a[sm] files are assembled with DAS, read DAS.DOC if you intend to assemble non-DC1 generated assembly. ------------------- OPTIONS ------------------ file File to compile, assemble (.a), and/or link (.o, .lib) @file File containing further list of files, one per line. (blank lines and lines beginning with ';' or '#' are ignored. File may NOT contain further options). -E file specify stderr file, any errors are appended to the file instead of to stdout. Useful for batch compiles -c Compile C source files and assemble into OBJECT files only (do not link). -a Compile C source files into ASSEMBLY files (do not assemble or link). Keep in mind the DAS will do further optimizations on the assembly file that you see. -l0 Do not link default libraries (dlib:c.lib dlib:amigas.lib dlib:auto.lib), or standard startup (dlib:c.o and dlib:x.o). BEGINNER'S NOTE: Do not use this option This option is used in special circumstances, such as when generating .libraries or .devices. WARNING: DICE is much more dependant on its startup code (c.o and x.o) than other compilers, do not link without the startup unless you know what you are doing. -l lib When linking include this library. (space is optional) Generally -l is used to include the math library (-lm) when formatted floating point *printf()s are required. -2.0 Default amiga.lib is dlib:amigas20.lib Default amiga include path is dinclude:amiga20/ -2.x where 'x' is the second digit replacing the '0' in the above example. This option is useful when compiling for different versions of the operating system. -1.4 Like -2.0, but using dlib:amigas14.lib and dinclude:amiga14/ Again, -1.x may be specified. -L0 remove default library search path, including all explicitly specified (-L dir) directories up to this point. -L dir add the specified directory to the library search path. If the object module or library can not be found in the current directory, directories specified with -L are searched. -L directories are searched before the default library directory (DLIB:), assuming it was not removed with -L0 . Note that the directory path specified by -L is used to search for libraries AND object modules. A trailing '/' is optional -I0 remove default include path from search list. The default include path is dinclude: and dinclude:amiga/ (unless modified by -1.x and -2.x options) -I dir When compiling scan this include directory (space is optional) The specified path takes precedence over defaults but defaults are NOT removed. -D define[=value] Pre-define a symbol -U undefine __STDC__, mc68000, _DCC, and AMIGA. BEGINNER'S NOTE: Do not use any of these options -o file Specify output executable, object, or assembly file name depending on what you are producing. The space is optional -020 generate code for the 68020 and later microprocessors -030 generate code for the 68030 and later microprocessors -881 generate inline FFP code for the 68881 -882 generate inline FFP code for the 68882 BEGINNER'S NOTE: Do not use any of these options These options exist to produce 020 and 030 opcodes, and 881/882 inline assembly for floating point operations. They are not necessarily implemented yet. The intent is to implement them by V2.06 . -md small data model (default) uses A4-relative -mD large data model uses absolute-long -mc small code model (default) uses PC-relative -mC large code model uses absolute-long BEGINNER'S NOTE: Use only -mD if you declare more than 64KBytes of data. These options specify the default data and code model to use. The model may be overriden by use of the __near and __far type qualifiers (see EXTENSIONS.DOC) on a variable by variable basis. DICE defaults to the small data and small code model, and is able to generate >32KBytes of code using the small code model so you should never have to use -mC. Note that the DICE libraries have all been compiled with the small-data model, and certain applications may disrupt the base register, A4... in this case use of the __geta4 type qualifier should be of use. If worse comes to worse you can recompile a large-data model C.LIB, but I suggest you try other solutions first. -ms0 (default), only const objects are put into a CODE hunk -ms string constants are put into the read-only code hunk -mS string constants are put into the read-only code hunk AND all external const references use NEAR addressing BEGINNER'S NOTE: Use only -ms -ms0 turns off -ms/-mS in case you have it in your DCCOPTS enviroment variable and want to turn it off. Default operation (no -ms or -mS) puts 'const' items into a read-only CODE hunk. Locally declared objects are referenced using PC-REL while external objects (declared in some other module) are referenced using 32-BIT ABSOLUTE addressing. -ms will additionally make all string constants, such as "fubar", const and referenced via PC-REL. -ms is an extremely useful option when you will never modify any of your string constants because the strings are not copied for multiple running instances of the program (if resident). -mS works like -ms, but in addition forces all external const references to use PC-REL addressing INSTEAD of 32-bit absolute addressing. THIS IS A VERY DANGEROUS OPTION, DO NOT USE UNLESS THE FINAL CODE SIZE IS LESS THAN 32 KBytes. Using -ms along with -r can result in huge savings of memory due to the string constants being moved out of the data segment (which must be duplicated for each running instance of the program). WARNING WARNING. In all cases if you declare an object as 'const' it must be extern'd as 'const' in other modules or incorrect code will be generated. This is true whether you use -ms/S or not. -mr registered arguments, light -mR registered arguments, medium -mRR registered arguments, strict BEGINNERS NOTE: either do not use these options or use only -mr BEGINNERS NOTE: see REGARGS.DOC These options control the automatic registerization of procedure arguments. Only those prototyped procedures declaring 4 or fewer arguments will be registered. Values are passed in D0/D1/A0/A1 according to the type of variable and availabilty of registers/ -mr generates entry points for both the registered argument and normal version of the function. This option is ideal for generating multi-model libraries. -mR generates only a single, registered entry point -mRR is similar to -mR but extends registerization to indirect function calls (that are fully prototyped). This is the most dangerous option. Note that -mr and -mR assign the normal, nonregistered entry point of a function to any indirect function pointers whether they are fully prototyped or not (e.g. void (*func)() or void (*func)(int) ) -mRR assigns either the registered or normal entry point to function pointers depending on whether they are prototyped or not (and any calls made through these function pointers will use the registered args method). WARNING: -mR CANNOT BE USED IF YOU MAKE C.LIB CALLS THAT TAKE CALL-BACK FUNCTIONS AS ARGUMENTS. -mr and -mRR *CAN* be used, however with -mRR you must be careful to supply the registered entry point. WARNING: AMIGA.LIB ROUTINES THAT TAKE CALL-BACK FUNCTIONS AS ARGUMENTS MUST BE GIVEN NON-REGISTERED ENTRY POINTS. Thus if you use -mRR you *must* qualify the procedure or function pointer type specification with __stkargs to entire it has a normal entry point. -mw <addr> USED FOR MAKING ROMABLE EXECUTABLES, DO NOT USE TO CREATE AMIGA EXECUTABLES BEGINNER'S NOTE: Do not use this option This option is another data model, called the ABSOLUTE-WORD data model. Source files compiled with this option generate absolute-word data references to access data objects instead of A4-relative or absolute-long. The base of the data segment must be specified as decimal, 0octal, or 0xHEX. Since absolute-word is used exclusive of A4-relative, the compiler will now use A4 for register variables. You may NOT mix -mw modules with small-data models (do NOT use C.LIB, see ROMABLE.DOC) The ROMABLE program is usually run on the executable generated by DLink to generate a ROM. -ma <addr> USED FOR MAKING ROMABLE EXECUTABLES, DO NOT USE TO CREATE AMIGA EXECUTABLES BEGINNER'S NOTE: Do not use this option This option specifies to the compiler and linker that the resulting code is intended to be relocated to a permanent data address, that specified by <addr> in decimal, 0octal, of 0xHEX. Unlike -mw, -ma assumes that the data segment can be placed anywhere. The ROMABLE program is usually run on the executable generated by DLink to generate a ROM. You may still specify a data model, -md or -mD, to use with this option. Unlike -mw, -ma does NOT touch the A4 register and thus may be mixed with the small-data model. Again, see ROMABLE.DOC -rom SET UP OPTIONS FOR GENERATING ROMABLE CODE BEGINNER'S NOTE: Do not use this option Like -l0, -rom disables automatic inclusion of a startup file (you must specify your own) and libraries. However, x.o is still included to sink any autoinit code. Your startup code must handle the appropriate model and call autoinit code before calling your program main This option is used to support ROMed firmware, i.e. non-amiga executables. You should never link with C.LIB. Instead, a new library, ROM.LIB, is available. ROM.LIB contains no static or global references and thus works with any data model, and only completely self-contained routines are included. The only data ROM.LIB uses is stack-based. All ROM.LIB routines are completely reentrant, including [v]sprintf() ! -proto PROTOTYPE CHECKING AND OPTIMIZATIONS When this option is used, an ERROR message will be generated for any call that is not prototyped. This option is useful to ensure that you have properly prototyped routines (when you use prototypes), especially when floats and doubles are passed and indirect function pointers are used (they must be prototyped as well!). IN THE FUTURE THIS WILL ENABLE STACK-ARGUMENT OPTIMIZATION. Currently, chars and shorts are extended to long's when pushed onto the stack for a subroutine call. In the future if the -proto option is used these objects will be pushed as shorts and not extended. -r Make executable residentable with separate CODE & DATA hunks -pr Make executable residentable w/ no relocation hunks -pi Make executable NON-residentable w/ no relocation hunks BEGINNER'S NOTE: Just use -r to get residentable executables and do not worry about these other options. -pr/-pi generate 'position independant' code also useful for ROMed applications. NOTE that -pi and -pr force const items to be referenced pc-relative as well, causing -ms and -mS to do the same thing (when combined with -pr/-pi) CODE SIZE IS LIMITED TO 32KBYTES WHEN YOU USE -pr OR -pi Refer to the section below called 'RESIDENTABILITY' for a discussion of these options NOTE ROPT1: You may not make data references within const declared objects when using the -r/-pr options. This is because the CODE hunk is shared between running instances of the program and these address references would be different between the instances. However, if you are using the -ms option, string constants will be in the code section and thus no problem. -O outdir Specify directory that is to contain output executable, object, or assembly files (used when specifying multiple source files) -O is useful to tell the compiler where to put the objects when you use dcc to compile and link a whole bunch of files at once. In this case, the -o option can still be used to specify where to put the final executable. NOTE: The -O name is used as a prefix so if you are specifying a directory be sure it has a ':' or '/' on the end. -T tmpdir Specify the temporary directory used to hold preprocessed source files and temporary assembly files... files that will be deleted after use. NOTE: The -T name is used as a prefix so if you are specifying a directory be sure it has a ':' or '/' on the end. The default is T: .. this option is useful in low-memory situations where you may decide to put intermediate files elsewhere. Putting intermediate files on your HD or floppy slows down compilation by an order of magnitude, but if you are running on a system with little memory you may not have a choice. -s Include symbolic debugging information in the executable. (dlink opion) This option includes the symbol table in the resulting executable and is passed to dlink. When using DOBJ to disassemble an executable, DOBJ will use the symbol table to generate a more symbolic dump. -S ALTERNATE SECTION NAMING OP FOR LIBRARIES When making libraries: uses alternate section naming conventions so that all initialized data in the module will be placed before any initialized data in non -S modules (i.e. normal linked object files). Any library BSS will be placed before non-library BSS. Thus, the final ordering in the final executable will be: [LIBDATA] [PROGRAMDATA] [LIBBSS] [PROGRAMBSS] Thus, if your program contains >64K Bytes of BSS you can still link with a library that tries to reference its own BSS using the small-data model. If your library declares only initialized data (i.e. int x = 0; ), then you can link with the library even if your program declares >64KBytes of *initialized* data ! -v Display commands as DCC executes them. -new Checks timestamps for source/destination and only compiles/assembles if object is outdated or does not exist. Used to make DCC a standalone make. -f FAST / ^C HANDLING FOR 1.3 This option is used for 1.3 only. You MUST be using the commodore shell (NewShell) and if you make programs resident you MUST use the commodore C:Resident command. This option will probably not work if you use WShell or ARPShell under 1.3. This option allows DICE to take short cuts to run sub-programs and allows ^C to be propogated to said programs. This option is useful to set permanently in your DCCOPTS ENV: variable if you run under 1.3 DICE under 2.0 has no such problems and will run sub programs optimally, including propogation of ^C. -frag FRAGment (linker option). Tell linker not to combine all code hunks together or combine all data hunks together. Cannot be used if the -r or -mw options are used. Generally only useful if the large-data model is used. Not entirely supported yet. -ffp Set fp library for floats BEGINNER'S NOTE: When using single precision floating point this option, use of the original ffp libraries, will make the program portable across all amigas. Otherwise only amigas that have the commodore MathIeeeSing*.library libraries will be able to run the program. If not specified, 'mathieeesingtrans.library' and 'mathieeesingbas.library' are used. These are new 2.0 libraries that may not exist on all machines yet. If specified, 'mathtrans.library' is used .. motorola's FFP float library. NOTE: IF -ffp is used, be warned that conversion from floats to doubles and back again is not entirely reliable. -d# Set debugging level (# = a number), used for compiler diagnostics only. -d<opts> Specify any combination of debugging options. These options may be combined in one -d option. Currently no options are defined. -gs Generate Dynamic Stack Code. This generates code on every subroutine call to check available stack. If available stack falls below 2K a new stack frame is allocated which will be deallocated when the subroutine returns. If the allocation fails, stack_abort() is called. If this routine is not defined by you, the library stack_abort() will call abort(). REFER TO DOC/EXTENSIONS.DOC FOR MORE INFO.cd src This option is extremely useful when compiling UNIX code that expects infinite stack. -chip CHIP force (linker option). Tell linker to force all hunks into CHIP memory. You should generally not use this option. Instead, use the __chip keyword (see EXTENSIONS.DOC) for those specific data items that need to be in CHIP memory. NOTE: CHIP data items are accessed using the large-data model, thus you cannot create residentable executables that contain __chip declarations UNLESS THEY ARE ALSO 'const' objects -- read-only. -aztec The front end attempts to run Aztec executables -lattice The front end attempts to run Lattice executables -sas same as -lattice These options allow one to write a single DMakefile able to handle compilation under any compiler, assuming the source is compilable under any compiler. These are very limited options and may not work across new versions of Aztec or Sas/C The ENV:DCCOPTS enviroment variable may contain additional options. ENV: must exist for DCC to run, even if you do not have a DCCOPTS enviroment variable. If you do not use ENV: then assign it to RAM: Example #1. Compile hello.c to executable. The objects will be left in T: 1> dcc hello.c -o ram:hello 1> ram:hello Example #2. Compile hello.c to executable and put the object file in X: 1> dcc hello.c -o ram:hello -TX: Example #3. Compile hello.c into object into RAM: then link with symbols 1> dcc -c hello.c -o ram:hello.o 1> dcc ram:hello.o -o ram:hello -s Example #4. Compile foo.c and link with an already compiled object file gar.o to produce an executable. foo.o is placed in T: 1> dcc foo.c gar.o -o ram:foogar PREPROCESSOR Predefined Symbols: __LINE__ current line number (integer constant) __DATE__ current date (string) __TIME__ current time (string) __FILE__ current file (string) __BASE_FILE__ base source file (string), allows specification of the actual name of the source file from within an include file. (-U undefines the below symbols) __STDC__ mc68000 _DCC AMIGA _FFP_FLOAT set if single prec. floats are in FFP format _SP_FLOAT set if single prec. floats are in IEEE-SING format (default) NOTE: There are no limits to symbol and macro lengths. MODELS DICE defaults to using the small-code and small-data models. You can use the small-code model even if your code is larger than 64K. However, to accomplish this DLINK uses one or more JUMP tables, and thus doing direct comparisons of the address of a given procedure may yield a different address depending on the module. If this is a problem you must either change the code or use the large-code model. The small-data model uses 16 bit A4-relative references to access static and global data. This has the advantage of making the executable smaller for two reasons: (1) each reference requires only one word of extension instead of two. (2) The linker is able to completely resolve the relative offsets and thus no relocation information is required in the final executable for such references. The small-data model also makes code run a bit faster. When you compile with the large-data model, note that the library code (C.LIB) still uses small-data references to access library based globals. This is normally not a problem since, due to the ordering of sections in the startup module, all library data occurs before user data and is thus within the A4 relative range. However, there is one problem that you might come up against... since BSS is always placed after initialized DATA, if you have more than 64KBytes of initialized data the linker may give up with an error due to library BSS being beyond the A4 relative offset range. PUTTING CONST DATA INTO THE CODE SEGMENT Two options are available to handle the 'const' keyword: -ms and -mS. If neither are used 'const' is ignored. The difference between the two determines how external references (between modules) are handled. With -ms, all string constants "fubar" are placed into the code segment and referenced according to the code model (pc-rel or absolute). Any variable declared const will also be put in the code segment and referenced similary. However, any EXTERN'd variables referenced but not defined in this module (i.e. defined in another module) will be accessed using ABSOLUTE references, since you cannot make a jump table for data variables. The -mS option is much more dangerous.. it works the same as -ms except that external references use pc-relative addressing as well. your final executable must be LESS THAN 32KBytes TO ENSURE ALL CODE IS REACHABLE VIA PC-RELATIVE ADDRESSING. If you have a choice, please use -ms instead of -mS . 'const __chip' variables will also be placed in the code section, but these always use absolute references since the code section is not combined together with other code sections. You may also override default access method (pc-rel/absolute) by using the __near and __far keywords, but this is not advised. The -ms option affects the main compiler DC1 and can be specified independantly for each source module (i.e. some can have it while others do not, though normally all will have it one way or the other) WHEN YOU USE -pr OR -pi, use of the -ms option is silently forced to -mS RESIDENTABILITY Two options are available to generate residentable executables and one option is available to genreate a non-residentable executable with no relocation information (loads quickly). RES? RELOC? DataLim CodeLim Alloc? Hunks -md no yes 64K(1) none no DATA, CODE -mD no yes none none no DATA, CODE, optionally more -r yes yes 64K none yes DATA, CODE -pr yes no 64K 32K yes CODE (combined DATA+CODE) -pi no no 64K 32K no CODE (combined DATA+CODE) RES: Can this program be made resident (dlink sets Pure bit) RELOC: Will this executable contain 32-bit relocations? DATALIM: The maximum amount of DATA+BSS that may be declared CODELIM: The maximum size of the CODE ALLOC: Does the startup code allocate a run time DATA+BSS segment? (basically, resident programs must, non-resident programs do not) HUNKS: Number and type of hunks that may exist in the executable -md default -mD used when final executable contains more than 64KBytes of data -r most often used option -pr used instead of -r if there is only a little initialized data Can be used with most programs but requires one large chunk of memory instead of the two smaller chunks that -r allocates Also used in ROMable applications -pi used instead of default when there is only a little INITIALIZED+BSS Can be used with many small programs that you do not intend to make residentable, to make them load extremely fast (since there is no relocation information). Also used in ROMable applications The __geta4 type qualifier will NOT work with residentable programs. You cannot use __far when accessing non-const (see -ms option) data in residentable programs USING THE -ms OPTION can drastically reduce the amount of data that needs to be allocated/copied when a resident program starts up by moving string constants into the code section (only the data section is duplicated), reducing overhead in both time and space for each invocation of the RESIDENT'd program. To use one of the options -r, -pi, or -pr specify on the DCC line when both compiling and linking your code. The resulting executable will have the pure bit set (for -r and -pr options) and be residentable. -r and -pr generate no BSS since the startup code is going to allocate the DATA+BSS space. -pi generates BSS space in the code segment just after the initialized data. default uses c.o -r uses c.o -pi uses c_pi.o -pr uses c_pr.o